Load a rulebase into the Determinations Engine
Understand the Determinations Engine rulebase data model
Understand the Determinations Engine inferencing cycle
Find out what data the Determinations Engine needs to make a decision
Pass data to the Determinations Engine
Get a decision from the Determinations Engine
Work with Determinations Engine data that changes over time
In the Oracle Determination Engine API, a rulebase must be loaded into the engine, before any of the rules written and compiled in that rulebase can be used. The com.oracle.determinations.engine.Engine class is responsible for loading a rulebase.
When loading a rulebase, you should pass the path (relative or absolute) to the rulebase archive (.zip) file. When you build the rulebase in Oracle Policy Modeling, this archive is automatically built in the rulebase project's output directory.
The rulebase archive name is always the name of the rulebase with a .zip extension. Once built, the rulebase archive can be moved out of the output directory of the rulebase. Nothing else is needed other than the Determinations Engine runtime files to execute the rules.
Rulebase simpleBenefits = engine.getRulebase("SimpleBenefits.zip");
Rulebase simpleBenefits = engine.GetRulebase("SimpleBenefits.zip");
When using the Determinations Engine API, it is important to understand how to interact with the engine in order to use a rulebase correctly.
The rulebase contains everything defined in Oracle Policy Modeling project: the rules, the data model used by the rules to reach determinations and screens can all be referenced through the rulebase. Typically, the first thing you do when interacting with the engine API is to load at least one rulebase
A session contains all the data that a rulebase will be used to use in determinations. Entity instances, attribute values for those instances in including inferred attribute values and relationships are all represented in the session.
After creating a session for a rulebase, you can set data, including entity instances, attributes and relationships to that session. Any inferred values are got from the session.
You may have several sessions from the same rulebase at the same time. Each session can have its own data, and will reach determinations based only on the data in that session.
Entities are defined when you create a rulebase using Oracle Policy Modeling. It represents a type of "thing" (for example a person). An entity can have attributes, and also relationships to other entities.
At runtime, you can create one or more instances of an entity; for example if your rulebase has a person entity, at runtime you might create one or more instances of the person entity. These entities represent data and will contain values for attributes, and may also be the source or targets of relationships.
All entity instances must be "contained" by another instance; for example, if the entity you want to create is contained by the global entity, then pass the Entity (type) you want to create as the first argument and the instance of the global entity as the second argument.
During runtime, an entity instance is created and held in the session.
In object oriented programming terms, an entity can be thought of as a class. It acts as a template to create instances, and an instance can be thought of as an object; an instantiation of the entity (class).
In this example, the global instance contains the child entity and is therefore required. The markContainmentComplete method indicates that all instances of the child entity have been collected; this method should be used after all entity instances of the child have been created.
EntityInstance global = session.getGlobalEntityInstance();
EntityInstance child1 = session.createEntityInstance(child, global);
global.markContainmentComplete(true, child);
Like entities, attributes are defined as part of authoring a rulebase in Oracle Policy Modeling. An attribute represents a simple value, like a number, or a text string and is always attached to an entity. When an entity instance is created, value for an attribute can be set for that instance. Each instance has its own value for every attribute defined for
Entity child = simpleBenefits.getEntity("child");
Attribute child_age = child.getAttribute("child_age");
child_age.setValue(child1, 16);
Depending on the type of attribute the value set will be different.
| Type | Java Type | C# Type |
|---|---|---|
| Number | java.lang.Double | System.Double |
| Currency | java.lang.Double | System.Double |
| Text | java lang.String | System.String |
| Date | java.util.Date | Oracle.Determinations.Masquerade.Util |
| DateTime | java.util.Date | Oracle.Determinations.Masquerade.Util |
| Time of Day | com.oracle.determinations.engine. DeterminationsEngineTimeOfDay | Com.Oracle.Determinations.Engine. DeterminationsEngineTimeOfDay |
Relationships are also defined as part of rulebase authoring. A relationship represents a connection between two types of entities with one end being the "source" and the other end representing the "target"; for example, a parent entity may have a one-to-many relationship to a child entity.
At runtime an instance of a relationship can be created to link entity instances together. Like an entity instance, relationship instances are created (and stored) in a session.
EntityInstance child1 = session.createEntityInstance(child);
EntityInstance child2 = session.createEntityInstance(child);
claimantschildren.setInstance(global,
Arrays.asList(new EntityInstance[] {child1, child2}));
The Inferencing Cycle is the cycle of question and answer which operates on rules to replicate the decision making process, as shown in the following illustration:
The diagram above shows the following steps:
The Inference Cycle will repeat steps 2 to 5 until the goal attribute is known.
When using Oracle Policy Automation within an application, you may need to determine what information is required to reach a particular determination or goal; for example, if you have a goal "the claimant is eligible for rent assistance", you may need to determine what information about the claimant is required to determine that outcome, so that you can retrieve it from a data source, or prompt the user to enter that information.
You can use a decision report to examine what data you need to determine a particular goal. A decision report can be used to determine how a particular answer was reached for a goal, but it can also be used to determine what information is needed to reach a decision.
A decision report is basically a tree of attributes and relationships that contributed to a decision. If a goal is Unknown, then one or more contributing attributes or relationships will also be unknown. By examining a decision report, and determining which of the base level attributes are unknown, you can tell what information you need to provide in order to obtain an answer for your goal.
Example: eligible teenage allowance
In the SimpleBenefits rulebase there are some simple rules for determining the goal ""
If we have a simple session with two child entities and no other attributes set, notice that the goal the claimant is eligible for the teenage child allowance is unknown.
If we investigate the attribute (right click and choose investigate) the decision report for the goal will be displayed. The decision report displays the relevant (contributing) attributes for the goal.
The decision report clearly shows the following:
So given this information, we can see that we need to provide the ages for the child instances.
If we set one of the children's age to 14, the goal becomes known. If we ask for a decision report (right click and choose Show Decision) we can see that the decision was reached because one child is a teenager, because their age is 14. The second child becomes irrelevant because for the goal to be true, we only need one teenage child.
For information regarding passing data to the Determinations Engine, refer to the topic, Understand the Determinations Engine rulebase data model.
The main function of the Determinations Engine is to be able to get an answer to a goals attribute (or a goal relationship) from a Determination Engine session. These goals will be inferred from the data that is provided to the session, using the existing rules in the rulebase.
There is a very simple process for obtaining the result (or decision) from a rulebase session; the procedure is as follows:
After the think() method is called on the session, the rules will fire, inferring all attributes and relationships that can be proved by the current rules and the data provided. Once the think has finished you can then get the value of the inferred attribute. The value returned will be in one of three states.
| State | Description | Return value |
|---|---|---|
| Known | A value was successfully inferred |
A value appropriate to the type of the attribute:
|
| Uncertain | The value of the attribute/relationship cannot be determined with the current data. | The value returned will be an instance of the com.oracle.determinations.engine.Uncertain class |
| Unknown | More information is needed to get a value | The value returned will be null |
session.think();
Attribute eligible_low_income_allowance = globalEntity
.getAttribute("eligible_low_income_allowance");
if (eligible_low_income_allowance.isUnknown(global)) {
System.out.println("eligible_low_income_allowance is unknown");
}
else if (eligible_low_income_allowance.isUncertain(global)) {
System.out.println("eligible_low_income_allowance is uncertain");
}
else {
Double value = (Double) eligible_low_income_allowance
.getValue(global));
System.out.println("eligible_low_income_allowance = "
+value);
}
If the value is known, then you have successfully inferred your goal. If the value is unknown, then more information is needed, you can use a decision report to work out what extra information you need to provide to obtain an answer.
If the value is uncertain, that means that because of the rules and data provided there is no way an answer can be provided, no matter how much more information you provide.
An example of an uncertain value might be "the age of the person's oldest child". Where the person has no children, the answer for this would be uncertain, as there is no number value that would make any sense.
It is possible to specify the values of an attribute that changes over time; for example, when putting in the values for a claimant's income, you may want to enter that data over a period of time where their income changed.
You can do this by setting the value of an attribute to a temporal value, using the classes in the com.oracle.determinations.engine.local.temporal package. Using these classes you can set different values of an attribute for different periods of time.
If we had a claimant who receives an annual income, we may want to represent that income as it varies over time.
We can represent these changes over time in the following way:
Attribute claimantsIncome;
EntityInstance claimant1;
...
// create the change point dates for the changes
ChangePointDate date1 = new ChangePointDate(2007, 5, 13);
ChangePointDate date2 = new ChangePointDate(2007, 6, 21);
// the temporal value has an initial value of 15000, and
// changes at date1 to 16000, and changes again at date2 to 12000
TemporalValue incomeVal = new TemporalValue(new Double(15000),
date1, new Double(16000),
date2, new Double(12000));
claimantsIncome.setValue(claimant1, incomeVal);
In the same way temporal values can be set through the engine API, you can also set values that vary over time in a Determinations Server request.
In this case we use the change-point element. The initial value for an attribute is the standard XML, but any variations to the value are contained in a change-point element.
The change-point elements must be put in ascending order (oldest to newest).
An empty value (meaning unknown) and a <uncertain-val/> element are also valid values.
<typ:attribute id="claimant_income">
<typ:number-val>15000</typ:number-val>
<typ:change-point date="2007-05-13">
<typ:number-val>16000</typ:number-val>
</typ:change-point>
<typ:change-point date="2007-06-21">
<typ:number-val>12000</typ:number-val>
</typ:change-point>
</typ:attribute>